PsL Monthly 1993 December

home *** CD-ROM | disk | FTP | other *** search

/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / pascal / keymakr.exe / KEYMAKER.DOC < prev next >

Wrap

Text File | 1990-10-07 | 35.3 KB | 1,094 lines

KeyMaker V2.0 Copyright 1990 Carl A. Franz - BabySitter JFL Consulting 1115 S. RidgeLand Oak Park, Il 60304 (708) 383-1546 CServe - 71041,1512 Purpose: The routines presented here facilitate the creation of a hash-keys for both names and addresses. The keys created are 'rational' and, using phonetic keymaking technology (Soundex), are tolerance of mis- spelling. This will allow you to create table or B-Tree keys in Turbo Pascal applications which are tolerant of your users. There are 3 general routines given here: 1) Whole Name 'key' generation. 2) Whole Address 'key' generation. 3) Single word 'Soundex' generation. This package comes with several files. To wit: KEYTOOLS.TPU - routines common to both the address and name 'keymaker' routines ADDRKEY.TPU - the address key build routine ADDRKEYL.PAS - the BUZZ word literal tables (appendix B) NAMEKEY.TPU - the name key build routine NAMEKEYL.PAS - the BUZZ word literal tables (appendix A) TESTAD.EXE - test program for AddrToKey TESTAD.PAS - source for TESTAD.EXE TESTKN.EXE - test program for NameToKey TESTKN.PAS - source for TESTKN.PAS Source for the TPU's come with registration. Be forewarned, the source is a mess but it works well. Registration will be explained on the last page of this document. (It's the same old thing). The phonetic keying system I use for individual words is called Soundex. It was, I believe, developed by AT&T Bell Labs. The concept and execution of the NameToKey and AddrToKey routines is proprietary to Carl A. Franz and JFL Consulting. TESTKN (for testing name key) and TESTAD (for testing address key) allow you to experiment with the KEYMAKER routines and learn how they work. I highly suggest you play with them before implementing KEYMAKER in your applications. Unfortunately, the only way to recompile the test routines is if you own the TTT toolbox for on screen field editing (etc.). The TTT Toolbox can, I believe, be found as Shareware on the Compuserve BPROGA forum Library 2. You can, however, rip out the formatted screen editing code and replace it with ReadLn's and then recompile when testing modifications to the BUZZ word tables. The programs contain comments on how to do this. History Most brilliant ideas come to you in the middle of the night when you least expect it. Not this one. This one was born of sheer necessity. I have two major character flaws: 1) I cannot remember anyone's birthdate or anniversary, and 2) I cannot spell worth a darn (this includes names). Thus I decided to let my computer remember for me (that is why God invented computers, isn't it?). In doing the analysis for the project I looked into varying methods of producing this filing system. Among the things neither prewritten applications nor Database packages do is phonetic key generation, auto-dialing of phone numbers, and/or decent mailing labels (for the most part). Certainly, not all within one package, and none at all with phonetic key generation and/or lookup... so I decided to write one. By the way, the filing system project is still not finished but this is the third utility package to be developed from it. Does anyone need a text screen or Pascal record compressor? Disclaimer This package is distributed on an AS-IS basis. No claim or warranty is implied as to it's fitness or suitability for any given application. I, as far as I know, made every effort to make sure the package works as advertised. As we all know, programming is an inexact science and bugs creep into programs from time to time. I will make every reasonable effort to fix any bugs (in my routines only) reported as quickly as possible and replace the defective product free of charge - as long as you are a registered user (or I like you [read 'polite']). If you run into any problems with this product, please report them to me with as much documentation as possible. You may report bugs via mail, phone (during reasonable evening and weekend CST hours), or Compuserve. The necessary information is on the first page of this document. Thank you for your support. Apologia Lord knows I did my best to document this. It may have even been overkill. I don't know. If, however, you still have a question of the usage or whatever, please contact me. I am proud of this effort. I think it words extremely well. I want people to use it (and more importantly to pay me for using it) so I'm fairly flexible in my support. NAMEKEY - NameToKey The purpose of this routine is to create a 10 character database lookup-key from a TP STRING which contains a name. None of this 3 or 5 field crap for each element of the name (first, last, middle initial, honorific, and title). Just type in the name as you would like to see it on an envelope, feed it into NameToKey and out comes a proper, rational key for table or data-base searches. Since the key returned is a 10 byte Pascal STRING, you can easily use it in MOST known TP database packages. Usage: VAR Name : STRING[40]; {or however long your name string is} NameKey : STRING[10]; FUNCTION NameToKey(Name : String) : String; {$V-} {Turn off strict string-checking} NameKey := NameToKey(Name); The key created from a name consists of three parts: LLLLLFFFFM where 'LLLLL' is the Soundex made from the last name, 'FFFFF' from the first name, and 'M' the middle initial (if any). For example, my name 'Mr. Carl A. Franz Esq.' will return a key of '1652 264 A'. '1652 ' is a Soundex of my last name (FRANZ), '264 ' is a Soundex of my first name, and of course 'A' is my middle initial. If only 1 word is found in the Name string it is assumed to be the last name and a key is generated accordingly. If your database tool box allows you to do CONTAINS or SUBSTRING key lookups you can use partial keys to for your searches. For instance, a name of 'FRANZ' will product a key of '1652 ' which can then be used to search for all FRANZ's. It will also find 'FRENZ' and several others I didn't think of. You must, of course, shorten the length of the KEY string to the last significant digit of the key (in this case 4 - NameKey[0] := ORD(4); or '1652') before doing a SUBSTRING or CONTAINS type database key search. You could also do 'Soundx('FRANZ',5)' which would also return '1652 ' (see the section on KEYTOOLS). As you can see, doing wider name searches can be accomplished simply by removing characters from the end of the key. This is in fact what I allow my users to do in my filing database system. When the user enters a name, I create a key from it and do a search and display a list of names which match the key. If the user cannot find the name they are looking for in the list they can hit the 'W' key and I lop off 4 characters of the key and try again. If they press 'W' again, I lop off three more characters. If they still cannot find the name I request that they try another spelling (sometimes Soundex doesn't work), or try another name because that one just isn't in the database. The NameKey Process The name key parsing routine goes through 6 steps to create a key: 1) Remove all punctuation. 2) Remove everything after '|' (explained later). 3) Remove all names Buzz words (see appendix B) from the name strings. 4) Use the last word remaining after step 3 as the last name. 5) Use the first word remaining after step 3 for the first name. 6) The second word first character is the middle initial. Example: 'Mr. Carl A. Franz Esq. DDS' (original name field) Step 1: 'Mr Carl A Franz Esq DDS' (remove punctuation) Step 2: 'Carl A Franz' (remove BUZZ words) Step 3: '264 A 1652' (Soundex remaining words) Step 4: Returns '1652 264 A' (Create key string) If you use part of the name field for notes (which I tend to do) such as 'Douglas Jandara | friend' the parsing routine of the NameToKey will ignore everything after the '|'. You, of course, do not need to use this feature if you don't want or need it. The next generation of this routine will contain everything necessary to parse and key company names ('Borland International Corp' for instance). If you think about corporate or business names as opposed to an individual names you will see just how complicated a task this will be. For one thing, for companies one tends to remember to first word of the name not the last as with individuals. Second, the list and variation of buzz words could be quite large. And thirdly, while is the case of 'BORLAND INTERNATIONAL CORP' you would remember 'BORLAND', in the case of 'ARTHUR ANDERSON CORP' you would remember the 'ANDERSON'. I am still analyzing this process and have made some progress. Registered users will have input to the process. ADDRKEY - AddrToKey Purpose: This routine creates a 13 character STRING key from a structure which contains an address. It works well but there are some rules which must be followed in order to make it work correctly. Read this and the next section carefully! Usage: TYPE AddrType = RECORD {standard address record description} Addr1 : String[40]; Addr2 : String[40]; City : String[15]; State : String[2]; Zip : string[5]; END; VAR AddrKey : STRING[13]; {the key string} Address : AddrType; {Structure declaration for AddrToKey} AddrS1, {Individual field declaration for } AddrS2 : STRING; { AddrToKeyNS. } ZipCodeS : String[5]; FUNCTION AddrToKey(AddrS1, AddrS2, ZipCodeS : String) : String; FUNCTION AddrToKeyT(Address : AddrType) : String; AddrKey := AddrToKeyT(Address); or: {$V-} {to turn off strict string checking} AddrKey := AddrToKey(addr1, addr2, zip); The reason I created 2 functions is ease of use. If you are already using, or are planning to use an address structure that is defined EXACTLY like ADDRTYPE (most I've seen do) then you may use the AddrToKeyT function. This will make your coding easier. If you have your own structure then you may pass the individual fields to the keymaker via AddrToKey. Anyway, both AddrToKey and AddrToKeyT accept address information from you and produce a 13 byte address key string. The key produced is structured like this: ZZZZZSSSSSNNA where ZZZZZ is zip code, SSSSS is street name Soundexed, NN is an integer hash of the street number (or box number), and A is a hash of the apartment number (apartment number 25 is a 7 (I just add the digits together)). The AddrKey Process The address parsing routine goes through 5 steps to create a key: 1) Normalize the incoming address strings. This involves 2 steps: A: Get rid of 'Attention' or 'Care OF' lines. B: If the address has both a street address and a PO Box number use whichever comes first. C: Get rid of all punctuation. D: Put the Zip Code into the key. 2) Remove all address Buzz words (see appendix B) from the address strings. 3) Find apartment words and number (or letter), remove them from the address strings. 4) If first of the words left is MOSTLY numeric, it is the street number, unless this is a PO BOX then the word after BOX is used as the street number. 5) The next word will be used as the street name, it will be Sondexed and inserted into the key. EXCEPT: if this is a PO BOX then 'BOX' is the street name, or if the if the street name is a number (as in 54ST or 31ST) and it will be inserted into the key as is. (REMEMBER: 33RD street IS 33RD ST. NOT Thirty-Third St.) There are several examples of the address keymaker processing in Appendix C. I'd put them here, but they would break up the flow of the narrative. One thing to be very careful of is that a Post Office Box can only be found if input as 'P.O. BOX' or 'PO BOX' and a number (or letter). If you were to enter an address as 'BOX 6' or P O BOX rather than 'PO BOX 6' the resulting key will not be what you expect. Try it using TESTAD.EXE. Unlike the NameToKey function, you will have to pay more attention to the BUZZ word literal tables in ADDRKEYL.PAS (see also Appendix B). For instance, unless you change the literal table, 'JCT' is the proper abbreviation for Junction, not 'JNCT' (see the 'Literal Tables' section for instructions on changing the literal tables). Any application you write using these routines will have to have some explanation of the standard abbreviations and what they are. (see also the 'Literal Tables' section) KeyTools Utilities The procedure and functions in the KEYTOOLS.TPU were not really written to be used other than by NameToKey or AddrToKey. They are really just a group of routines which are common to both functions. They are, however, useful little devils. So, what the heck, think of them as a bonus. FUNCTION Soundx(InWord : string; cnt : integer) : string; This function creates a Soundex type phonetic representation of a word. InWord - the word you want 'Soundexed'. Cnt - max number of characters in the returned string. Returns : a Soundex of InWord no longer than Cnt characters. FUNCTION InTable(VAR Fword;VAR Stable; tsize: integer) : Boolean; This functions does a binary search on any sorted table which contains, as elements, 8 character strings. Fword - the word you wish to find. Stable - the table to be searched (for Fword) tsize - the number of elements in the table Returns : true if Fword is found in Stable - else false FUNCTION ExtWord(WordNum : byte; InStr : string) : string; This function extracts a word from a string. WordNum - the number of the word within the string to extract and return. InStr - The string from which to extract the word Returns : The word to be extracted or a null string if you ask for the 10th word and there are only 8. FUNCTION CntWord(InStr : string) : Integer; This function returns the number of space separated words in a string. InStr - the string. Returns : an integer containing the number of words in InStr. If these routines are of any help...Great. If not, so what. Literal Tables This section may be a bit confusing at first. You may want to read it several times before attempting to edit the BUZZ word tables in ADDRKEYL.PAS and NAMEKEYL.PAS. A listing of the literal tables in ADDRKEYL.PAS and NAMEKEYL.PAS is found on the next several pages. These tables contain words or abbreviations which are common to, or are found in conjunction with, either names or addresses (depending on table). The keymaker uses these tables to either remove words which inhibit the creation of PROPER name or address keys OR mark items which are necessary to the key (like the Apartment table helps me find the apartment number). You are free to change these tables as you see fit. In doing so you MUST remember a few things: 1) All words must be completely in uppercase characters. 2) They must be in sorted order (remember that in ASCII numbers come before letters). 3) Any table entry which you remove from these tables increases the likelihood that a key will be incorrectly created. For instance, were you to remove 'CPA' from the Honorifics table and a key for the name 'Carl A Franz CPA' were created, the key would use 'CPA' for the last name, not 'FRANZ' because it would not recognize 'CPA' as a name BUZZ word and remove it. 4) Most of the words in these BUZZ word tables are abbreviations for common words within their domain (address or name). You may want to add the full word to the table for cases where you feel your users (the users of your particular application) would possibly use the full word rather than the abbreviation. While I feel these table is complete, a common reason for changing them is to add foreign language or regionally peculiar address or name words. If you feel that you MUST cut the BUZZ word tables down in order to conserve DATA SEGMENT space, the first place I would consider is the plethora of military designations in the Titles table. After that, I'd look in the Honorifics (I don't know of anyone who is a CLU -- 'Certified Licensed Underwriter' -- but your users may!). The BUZZ word tables are as large as they are for COMPLETENESS. 90% of the analysis time spent in building this product was spent compiling these tables. You may, as you see fit, cut them down a bit, add to them, or leave them alone. If you do decide to modify them... BE CAREFUL! I had considered writing a program which facilitates the maintenance of these tables. Currently, however, I am working on the Company name side of the NameToKey function and don't have the time. Oh well. Appendix A Name Type BUZZ Words Titles Honorifics Abbreviations Meanings Abbreviations Meanings '1ST' First 'AL' (as in Et. Al.) '2ND' Second 'ASST' Assistant 'ADMIRAL' Admiral 'ATTY' Attorney 'AG' Adjutant General 'CEO' Chairman of the Board 'AMB' Ambassador 'CHAIRMAN' Chairman 'AMN' Airman 'CHAPLAIN' Chaplain 'ATTY' Attorney 'CLU' Cert Licensed Underwriter 'BRIG' Brigadeer 'CPA' Certified-Public-Accountant 'CMDR' Commander 'CPAS' CPA plural 'CMSGT' Chief Master Sgt 'DA' District Attorney 'COL' Colonel 'DD' Dr of Divinity 'CPL' Corporal 'DDS' Dentist 'CPO' Chief Petty Officer 'DMD' Dental DR 'CPT' Captain 'DR' Doctor 'CWO' Chief Warrant Off 'DVM' Veterinary Dr 'ESQ' Esquire 'DR' Doctor 'ET' (as in Et. Al.) 'DRS' Doctors 'EXEC' Executor 'ENS' Ensign 'GOV' Governor 'FR' Friar 'II' the Second 'GEN' General 'III' the Third 'GENERAL' General 'IV' the Fourth 'GOV' Governor 'JP' Justice o/t Peace 'GYSGT' Gunnery Sgt 'JR' Junior 'HON' Honor/Honorable 'LLB' Master Of Laws 'JDG' Judge 'LLD' Doctor Of Laws 'JG' Junior Grade 'LT' Lieutenant 'LCDR' Lieutenant Cmmdr 'MD' Medical Doctor 'LCPL' Lance Corporal 'LT' Lieutenant 'PERSONAL' Personal 'M/SGT' Master Sergeant 'PHD' has a Doctorate 'MAJ' Major 'PHYS' Physician 'MCPO' Master CPO 'PRES' President 'MISS' MISS 'RA' Rear Admiral 'MOTHER' Mother 'REP' Representative 'MR' Mister 'RET' Retired 'MRS' Misses 'RN' Registered Nurse 'MS' MS 'RVN' Reg. Vocat. Nurse 'MSGR' Monsignor 'SR' Senior 'PFC' Private/First Class Appendix A Name Type BUZZ Words Titles abbreviations Meanings 'PROF' Professor 'PSGT' Platoon Sgt 'PVT' Private 'RABBI' Rabbi 'REP' Representative 'REV' Reverend 'REVEREND' Reverend 'RT' Retired 'S/SGT' Staff Sergeant 'SA' Seaman Apprentice 'SCPO' Senior CPO 'SEN' Senator 'SFC' Sergeant First Class 'SGT' Sergeant 'SISTER' Sister 'SMN' Seaman 'SMSGT' Senior Master Sgt 'SR' Senior 'SSM' Staff Sgt. Major 'T/SGT' Technical Sgt 'WO' Warrant Officer Appendix B Address Type BUZZ Words abbreviations Meanings abbreviations Meanings 'ALLEY' Alley 'MDWS' Meadows 'ALY' Alley 'MNR' Manor 'ANX' Annex 'MTN' Mountain 'APTS' Apartments 'N' North 'ARC' Arcade 'NAS' Navel Station 'AV' Avenue 'NE' North East 'AVE' Avenue 'NW' North West 'BCH' Beach 'OF' Of 'BLDG' Building 'ORCH' Orchard 'BLVD' Boulevard 'OVAL' Oval 'BYU' Bayou 'PALMS' Palms 'BOX' BOX 'PARK' Park 'CIR' Circle 'PASS' Pass 'CLG' College 'PATH' Path 'CMM' Common 'PK' Park 'CMMS' Commons 'PKWY' Parkway 'CONDO' Condominium 'PL' Place 'COR' Court 'PLZ' Plaza 'COURT' Court 'PO' Post Office 'CP' Camp 'PRT' Port 'CRES' Crescent 'PT' Point 'CT' Court 'RD' Road 'CTL' Central 'RDWY' Roadway 'CTR' Center 'RR' Rural Route 'CTS' Courts 'RT' Route 'CYN' Canyon 'S' South 'DR' Drive 'SCH' School '1/2' One Half 'SE' South East 'E' East 'SHR' Shore 'EST' Estates 'SHRS' Shores 'EXPWY' Expressway 'SPDWY' Speedway 'EXPY' Expressway 'SPG' Spring 'EXT' Extension 'SPGS' Springs 'FWY' Freeway 'SQ' Square 'GDNS' Gardens 'ST' Street 'GR' Green 'STA' Station 'HBR' Harbor 'SW' South West 'HL' Hill 'TER' Terrace 'HLS' Hills 'TERR' Territory/Terrace 'HOLW' Hollow 'TPKE' Turnpike 'HOSP' Hospital 'TR' Trail 'HSE' House 'TUNL' Tunnel 'HTS' Heights 'TWN' TownShip 'HWY' Highway 'TWR' Tower 'JCT' Junction 'TWRS' Towers 'LA' Lane 'US' US 'LK' Lake 'VL' Village 'LKS' Lakes 'VLG' Village 'LN' Lane 'VLY' Valley 'LNDG' Landing 'W' West 'LWR' Lower 'WAY' Way 'MALL' Mall 'WTR' Water 'MDL' Middle 'WY' Way Address Keymaker Examples Each of these examples takes you through the steps the address keymaker goes through in order to create a key. The first address in each example grouping is the user input, the rest follow the steps outlines in 'The AddrKey Process section. A couple of things first: 1) Because the street number is a TP Integer I will suggest it's inclusion into the key with a '##'. 2) The street name is Sondexed, that's why it shows up as numbers. Key State Address Parsing Comments ZZZZZSSSSS##A Addr1: 'C/O: JFL Consulting ' (User input) (cleared) Addr1: '1115 S. Ridgeland Ave. Apt #2' Zip: '60304' Addr1: '' (normalize) 60304 Addr1: '1115 S Ridgeland Ave Apt 2' Addr1: '' (buzz words) 60304 Addr1: '1115 Ridgeland Apt #2' Addr1: '' (apartment words 60304 2 Addr1: '1115 Ridgeland' and number) Addr1: '' (Street number) 60304 ##2 Addr1: 'Ridgeland' Addr1: '' (Street name) 6030416536##2 Addr1: '' Key State Address Parsing Comments ZZZZZSSSSS##A Addr1: 'P.O. Box 315 ' (User Input) (cleared) Addr1: '1115 S. Ridgeland Ave. Apt #2' Zip: '60304' Addr1: 'PO Box 315 (normalize) 60304 Addr1: '' 60304 Addr1: 'BOX 315' (buzz words) Addr1: '' 60304 Addr1: 'BOX 315' (apartment words Addr1: '' 60304 ## Addr1: 'BOX' (Street or Box Addr1: '' number) 60304BOX ## Addr1: '' (Street name Addr1: '' 'BOX' in this case) Address Keymaker Examples Key State Address Parsing Comments ZZZZZSSSSS##A Addr1: '1115 S. Ridgeland Ave. Apt #2' (User Input) (cleared) Addr1: 'P.O. Box 315 ' Zip: '60304' Addr1: '1115 S Ridgeland Ave Apt 2' (normalize) 60304 Addr1: '' Addr1: '1115 Ridgeland Apt 2 (buzz words) 60304 Addr1: '' Addr1: '1115 Ridgeland' (apartment words 60304 2 Addr1: '' Addr1: 'Ridgeland' (Street or Box 60304 ##2 Addr1: '' number) Addr1: '' (Street name) 6030416547##2 Addr1: '' case) Key State Address Parsing Comments ZZZZZSSSSS##A Addr1: '128 W. 34th St. Apt #2A ' (User Input) (cleared) Addr1: '' Zip: '60304' Addr1: '128 W 34th St Apt 2A ' (Normalize) 60304 Addr1: '' Addr1: '128 34th apt 2A ' (buzz words) 60304 Addr1: '' Addr1: '128 34th ' (apartment words 60304 3 Addr1: '' Addr1: '34th ' (Street or Box 60304 ##2 Addr1: '' number) Addr1: '' (Street name) 6030434TH ##2 Addr1: '' JFL Consulting - Registration Mailer Please supply us with the following information: Your Name _________________________________________________________________ ___ Street Address _______________________________________________________________ City, State and Zip Code _____________________________________________________ Country _________________________________________________________________ _____ Voice Phone (_____) _____-_______ if in USA, otherwise ____-___-_____-________ COST TOTAL QTY PRODUCT DESCRIPTION EACH PRICE ------- --------------------------------------------- -------- --------- _______ _KeyMaker Registration ______________________ __10.00_ _________ _______ _Keymaker Registration With Source___________ __18.00_ _________ _______ _KeyMaker v3.0 Upgrade (when-available)______ ___5.00_ _________ _______ _____________________________________________ ________ _________ _______ _____________________________________________ ________ _________ _______ _____________________________________________ ________ _________ SUBTOTAL _________ (Illinois residents only) 7.0% TAX _________ GRAND TOTAL _________ Method of Payment: [ ]-Check [ ]-Money Order (no C.O.D.s please) Comments _________________________________________________________________ ____ _________________________________________________________________ _____________ _________________________________________________________________ _____________ _________________________________________________________________ _____________ Fold at the page break below with the printing facing out. Then fold letter style, exposing the mailing address and hiding your information. Staple your check (if used) to the mailer, then staple or tape sides and top. _________________________________ ┌───────┐ │ │ _________________________________ │ PLACE │ │ STAMP │ _________________________________ │ HERE │ │ │ _________________________________ └───────┘ Carl A. Franz JFL Consulting 1115 S. Ridgeland Ave. Oak Park, Il 60304 Attn: Babysitter _________________________________________________________________ _______________ _________________________________________________________________ _______________ ----------------end-of-author's-documentation--------------- Software Library Information: This disk copy provided as a service of Public (software) Library We are not the authors of this program, nor are we associated with the author in any way other than as a distributor of the program in accordance with the author's terms of distribution. Please direct shareware payments and specific questions about this program to the author of the program, whose name appears elsewhere in this documentation. If you have trouble getting in touch with the author, we will do whatever we can to help you with your questions. All programs have been tested and do run. To report problems, please use the form that is in the file PROBLEM.DOC on many of our disks or in other written for- mat with screen printouts, if possible. PsL cannot debug pro- programs over the telephone, though we can answer questions. Disks in the PsL are updated monthly, so if you did not get this disk directly from the PsL, you should be aware that the files in this set may no longer be the current versions. Also, if you got this disk from another vendor and are having prob- lems, be aware that some files may have become corrupted or lost by that vendor. Get a current, working disk from PsL. For a copy of the latest monthly software library newsletter and a list of the 2,000+ disks in the library, call or write Public (software) Library P.O.Box 35705 - F Houston, TX 77235-5705 1-800-2424-PSL MC/Visa/AmEx/Discover Outside of U.S. or in Texas or for general information, Call 1-713-524-6394 PsL also has an outstanding catalog for the Macintosh.